Supplementary media

Here you will find details about:

The supplementary media for a Multimedia record is stored in a directory called supplementary under the directory in which the master image is stored on the EMu server. The location of the master image is determined by the ServerMediaPath Registry entry (or in the absence of this entry, the ServerPath Registry entry entry). The Registry entry contains a list of paths to consult when locating multimedia on the EMu server. The first path in the Registry entry is used to store new multimedia, while all paths are searched to locate multimedia.

There is a special case in which an exec entry may be used to interface between EMu and a third party imaging system (see Integrating 3rd party imaging systems for more details). In order to support supplementary media while still maintaining the same interface to third party systems, the filepath supplied to the get, save, ping and remove calls may now include the supplementary directory. For example, the file path passed to the ping call for a supplementary image called Image.jpg for the Multimedia record with IRN 4254 would be:

4/254/supplementary/Image.jpg

The list call should now return not only all media in the folder passed to it, but all media in the supplementary directory. For example, the call list 4/254 may result in the following response being returned:

Status: success
4/254/master.jpg
4/254/master.thumbnail.jpg
4/254/master.300x300.jpg
4/254/supplementary/video.avi
4/254/supplementary/image.tif\

Supplementary media may be accessed from IMu via the virtual Supplementary column in the Multimedia module. The PHP code below returns all supplementary media for the Multimedia record with IRN 965:

$module = new IMuModule('emultimedia', $session);
$module->findKey(965);
$columns = array
(
    'irn',
    'supplementary'
);
$result = $module->fetch('start', 0, 1, $columns);
$supplementary = $result->rows[0]['supplementary'];

The data structure returned is an array in which each entry represents one row in the Supplementary table. For example:

Array
(
    [0] => Array
        (
            [width] => 468
            [usage] => Array
                (
                    [0] => Web,
                    [1] => Crop,
)
            [mimeFormat] => jpeg
            [height] => 600
            [size] => 31073
            [index] => 4
            [identifier] => spear head.jpg
            [kind] => supplementary
            [fileSize] => 31073
            [notes] => A cropped image of the spear head.
            [mimeType] => image
            [md5Sum] => 5a7147c4f27ced997458b8171f2a44a6
            [md5Checksum] => 5a7147c4f27ced997458b8171f2a44a6
            [supplementary] => 0/007/supplementary/spear head.jpg
)
    [1] => Array
        (
            [width] => 468
            [usage] => Array
                (
                    [0] => Web
)
            [mimeFormat] => jpeg
            [height] => 600
            [size] => 27584
            [index] => 5
            [identifier] => spear handle.jpg
            [kind] => supplementary
            [fileSize] => 27584
            [notes] => A cropped image of the spear handle.
            [mimeType] => image
            [md5Sum] => ff57b2f343df44c4c8979cfd2d1f45d2
            [md5Checksum] => ff57b2f343df44c4c8979cfd2d1f45d2
            [supplementary] => 0/007/supplementary/spear handle.jpg
)
)

To get a filtered list, a filter may be added to the column name. Filters are specified in parentheses after the column name. It's possible to filter on almost any value that comes back (with the exception of notes). So, if we only want supplementary media with images, the following PHP code segment could be used:

$columns = array
(
    'irn',
    'supplementary(mimeType=image)'
);

The filter reduces the set of supplementary media to only those that are images. It's possible to specify multiple filters. For example, if you only want JPEG images, the following column construct could be used:

supplementary(mimeType=image;mimeFormat=jpeg)

or if you want all images except TIFFs:

supplementary(mimeType=image;mimeFormat!=tiff)

or if you want non-TIFF images with a width over 300 pixels:

supplementary(mimeType=image;mimeFormat!=tiff;width>300)

All of these filters simply discard supplementary entries from the result set which do not match the specified criteria.

Two other operators are available:

  • @
  • ^

If you want the single image which is closest to 300 pixels wide, use:

supplementary(mimeType=image;width@300)

This will return only one entry (at most), which is the image which is closest to 300 pixels wide (may be bigger or smaller than 300).

If you want to get the image that is closest to but bigger than 300 pixels, use:

supplementary(mimeType=image;width^300)

All these filters return information associated with the resource but not the resource itself. If you want the resource as well, the following construct is required:

supplementary(mimeType=image;width^300){resource:include}

This will return a structure that looks like:

Array
(
    [0] => Array
        (
            [width] => 468
            [usage] => Array
                (
                    [0] => Web
)
            [mimeFormat] => jpeg
            [height] => 600
            [size] => 31073
            [resource] => Array
                (
                    [width] => 468
                    [identifier] => spear head.jpg
                    [file] => Resource id #12
                    [mimeFormat] => jpeg
                    [mimeType] => image
                    [height] => 600
                    [size] => 31073
)
            [index] => 4
            [identifier] => spear head.jpg
            [kind] => supplementary
            [fileSize] => 31073
            [notes] => A cropped image of the spear head.
            [mimeType] => image
            [md5Sum] => 5a7147c4f27ced997458b8171f2a44a6
            [md5Checksum] => 5a7147c4f27ced997458b8171f2a44a6
            [supplementary] => 0/007/supplementary/spear head.jpg
)
)

Notice there is now a resource entry. This includes information about the resource and, most importantly, includes an open file handle to the resource contents (file attribute).

If you want the resource to be reformatted in some way, you can specify the reformatting in the same way as you can for the existing resource column. For example, if you want the resource as a 200x200 gif, use:

supplementary(mimeType=image;width^300){resource:include;format:gif;width:200;height:200}

This works just as before, but with the reformatted image as the resource:

Array
(
    [0] => Array
        (
            [width] => 468
            [usage] => Array
                (
                    [0] => Web
)
            [mimeFormat] => jpeg
            [height] => 600
            [size] => 31073
            [resource] => Array
                (
                    [width] => 156
                    [identifier] => spear head.gif
                    [file] => Resource id #12
                    [mimeFormat] => gif
                    [mimeType] => image
                    [height] => 200
                    [size] => 18917
)
            [index] => 4
            [identifier] => spear head.jpg
            [kind] => supplementary
            [fileSize] => 31073
            [notes] => A cropped image of the spear head.
            [mimeType] => image
            [md5Sum] => 5a7147c4f27ced997458b8171f2a44a6
            [md5Checksum] => 5a7147c4f27ced997458b8171f2a44a6
            [supplementary] => 0/007/supplementary/spear head.jpg
)
)